개요

첫번째로 진행하는 실습은 기본적인 클러스터를 구축하고 다른 CNI에서 마이그레이션하여 실리움을 설치하는 것이다.
인스턴스 프로비저닝은 Vagrant와 virtualbox를 이용한다.
클러스터 구축은 kubeadm을 사용하는데, 모든 설정 정보를 설정 파일을 기반으로 관리할 것이다.
초기 cni로는 flannel을 이용하며 클러스터를 재구축하지 않고 롤아웃 방식으로 실리움 마이그레이션을 거칠 것이다.
(flannel에 대해서는 이번 지면에서 부연하지 않으나 매우 간단한 수준에서 CNI의 스펙을 만족하는 프로바이더라고만 알면 될 듯하다.)

인스턴스 세팅

기본적인 코드는 전부 가시다님이 제공해주신 스크립트라 자세히 다루지는 않겠다.
코드는 전부 레포에 담기니 참고하자.
이 Vagrantfile을 이용해 vagrant up을 해주면 된다.

K8SV = '1.33.2-1.1'
CONTAINERDV = '1.7.27-1'
N = 2 # max number of worker nodes

BOX_IMAGE = "bento/ubuntu-24.04"
BOX_VERSION = "202502.21.0"
## Rocky linux Image https://portal.cloud.hashicorp.com/vagrant/discover/rockylinux
# BOX_IMAGE = "rockylinux/10"
# BOX_VERSION = "0.0.0"

Vagrant.configure("2") do |config|
  if Vagrant.has_plugin? "vagrant-vbguest"
    config.vbguest.no_install  = true
  end
#-ControlPlane Node
  config.vm.define "k8s-ctr" do |subconfig|
    subconfig.vm.box = BOX_IMAGE
    subconfig.vm.box_version = BOX_VERSION
    subconfig.vm.boot_timeout = 120
    subconfig.vm.provider "virtualbox" do |vb|
      vb.customize ["modifyvm", :id, "--groups", "/Cilium-Lab"]
      vb.customize ["modifyvm", :id, "--nicpromisc2", "allow-all"]
      # solving ssh timeout sometimes
      vb.customize ["modifyvm", :id, "--uart1", "0x3F8", "4"]
      vb.customize ["modifyvm", :id, "--uartmode1", "file", File::NULL]

      vb.name = "k8s-ctr"
      vb.cpus = 2
      vb.memory = 2048
      vb.linked_clone = true
    end
    subconfig.vm.host_name = "k8s-ctr"
    subconfig.vm.network "private_network", ip: "192.168.10.100"
    subconfig.vm.network "forwarded_port", guest: 22, host: 60000, auto_correct: true, id: "ssh"
    subconfig.vm.synced_folder "./", "/vagrant", disabled: true
    subconfig.vm.provision "file", source: "./kubeadm-config/init-cfg.yaml", destination: "/tmp/init-cfg.yaml"
    subconfig.vm.provision "shell", path: "init_cfg.sh", args: [ K8SV, CONTAINERDV]
    subconfig.vm.provision "shell", path: "k8s-ctr.sh", args: [ N ]
  end

#-Worker Nodes Subnet1
  (1..N).each do |i|
    config.vm.define "k8s-w#{i}" do |subconfig|
      subconfig.vm.box = BOX_IMAGE
      subconfig.vm.box_version = BOX_VERSION
      subconfig.vm.boot_timeout = 120
      subconfig.vm.provider "virtualbox" do |vb|
        vb.customize ["modifyvm", :id, "--groups", "/Cilium-Lab"]
        vb.customize ["modifyvm", :id, "--nicpromisc2", "allow-all"]
        vb.customize ["modifyvm", :id, "--uart1", "0x3F8", "4"]
        vb.customize ["modifyvm", :id, "--uartmode1", "file", File::NULL]
        vb.name = "k8s-w#{i}"
        vb.cpus = 2
        vb.memory = 2048
        vb.linked_clone = true
      end
      subconfig.vm.host_name = "k8s-w#{i}"
      subconfig.vm.network "private_network", ip: "192.168.10.10#{i}"
      subconfig.vm.network "forwarded_port", guest: 22, host: "6000#{i}", auto_correct: true, id: "ssh"
      subconfig.vm.synced_folder "./", "/vagrant", disabled: true
      subconfig.vm.provision "file", source: "./kubeadm-config/join-cfg.yaml", destination: "/tmp/join-cfg.yaml"
      subconfig.vm.provision "shell", path: "init_cfg.sh", args: [ K8SV, CONTAINERDV]
      subconfig.vm.provision "shell", path: "k8s-w.sh", args: [i]
    end
  end
end

몇가지 커스텀을 한 부분은 설정 파일을 위해 워커 노드를 설정하는 스크립트에 추가 인자로 i를 전달한 것.

박스 이미지마다 케이스가 매번 다른 것으로 보이는데, ssh 키를 만들고 연결을 맺는 과정에서 간혹 프로비저닝이 완전히 중지돼버리는 케이스가 있다.
어쩔 때는 껐다 키면 되고, 어쩔 때는 계속 안 되는 등 간헐적이면서도 명확한 에러의 원인이 출력되지 않기에 원인을 진단하기 어려워 아직 해결하지 못한 것들이 많다.
가장 핵심적으로 발생하는 문제는 ssh 키를 주입하는 과정에서 타임아웃이 나는 건데, 어떤 글에서는 대화형 입력이 들어가게 만들어야 한다느니 gui면 키면 된다느니 하지만 간헐적으로 발생하는 이유에 대한 명쾌한 해답이 주어지진 않는다.
이런 식으로 문제를 해결했다는 글이 있어 시도를 해봤으나, 역시 이것도 정답은 아니었다.^[1]
아무튼 안 된다 싶으면 대충 몇 번 재시도해보면 된다.
(여태 봤을 때 우분투 이미지를 쓸 때만 문제가 발생하는 것 같다.)

아울러 rocky linux로 세팅을 해보려고 했으나, 이전에도 말썽이더니만 이번에도 박스 이미지가 제대로 기동되지 않았다.
almalinux로 하면 그런 문제가 없는 것을 이전에 확인했기 때문에 추후 almalinux로 바꾸어서 하는 것도 좋겠다.

클러스터 구축

초기 스크립트로 인해 바로 클러스터가 구축된다.

전체 스크립트는 레포를 확인한다.
kubeadm으로 설치할 때 설정 파일을 이용하여 세팅을 진행했다.

apiVersion: kubeadm.k8s.io/v1beta4
bootstrapTokens:
  - groups:
      - system:bootstrappers:kubeadm:default-node-token
    token: "123456.1234567890123456"
    ttl: 24h0m0s
    usages:
      - signing
      - authentication
kind: InitConfiguration
localAPIEndpoint:
  advertiseAddress: 192.168.10.100
  bindPort: 6443
nodeRegistration:
  criSocket: unix:///run/containerd/containerd.sock
  imagePullPolicy: IfNotPresent
  imagePullSerial: true
  name: k8s-ctr
  kubeletExtraArgs:
    - name: node-ip
      value: 192.168.10.100
  taints: null
timeouts:
  controlPlaneComponentHealthCheck: 4m0s
  discovery: 5m0s
  etcdAPICall: 2m0s
  kubeletHealthCheck: 4m0s
  kubernetesAPICall: 1m0s
  tlsBootstrap: 5m0s
  upgradeManifests: 5m0s
---
apiServer:
  extraArgs:
    - name: bind-address
      value: "0.0.0.0"
apiVersion: kubeadm.k8s.io/v1beta4
caCertificateValidityPeriod: 87600h0m0s
certificateValidityPeriod: 8760h0m0s
certificatesDir: /etc/kubernetes/pki
clusterName: kubernetes
controlPlaneEndpoint: "192.168.10.100:6443"
controllerManager: {}
dns: {}
encryptionAlgorithm: RSA-2048
etcd:
  local:
    dataDir: /var/lib/etcd
imageRepository: registry.k8s.io
kind: ClusterConfiguration
kubernetesVersion: 1.33.0
networking:
  dnsDomain: cluster.local
  podSubnet: 10.244.0.0/16
  serviceSubnet: 10.96.0.0/16
proxy: {}
scheduler: {}

kubeadm config print init-defaults 명령을 치면 나오는 기본값에서 실습에 사용될 몇 가지 필드만 수정해서 넣어주었다.
nodeRegistration에 kubelet node-ip 설정을 해주는 게 매우 중요하니 해당 부분은 꼭 넣어주도록 하자.

join 설정 파일도 마찬가지인데, placeholder를 두어 각 워커 노드에 커스텀할 수 있는 방식을 사용하신 분이 있어 이 분의 코드를 적극 활용했다.

apiVersion: kubeadm.k8s.io/v1beta4
caCertPath: /etc/kubernetes/pki/ca.crt
discovery:
  bootstrapToken:
    apiServerEndpoint: 192.168.10.100:6443
    token: "123456.1234567890123456"
    unsafeSkipCAVerification: true
kind: JoinConfiguration
nodeRegistration:
  criSocket: unix:///run/containerd/containerd.sock
  imagePullPolicy: IfNotPresent
  imagePullSerial: true
  name: "NODENAME_PLACEHOLDER"
  kubeletExtraArgs:
    - name: node-ip
      value: "IP_PLACEHOLDER"
  taints: null
timeouts:
  controlPlaneComponentHealthCheck: 4m0s
  discovery: 5m0s
  etcdAPICall: 2m0s
  kubeletHealthCheck: 4m0s
  kubernetesAPICall: 1m0s
  tlsBootstrap: 5m0s
  upgradeManifests: 5m0s

확인

vm 정보 확인

한 vm에 들어가 각종 정보를 확인해본다.

# nic 정보
ip -c addr
# vagrant ssh 로 접속 시 tcp 연결 정보 : NAT Mode 10.0.2.2(GateWay)
ss -tnp |grep sshd
# default 라우팅 정보 
ip -c route
# dns 서버 정보 : NAT Mode 10.0.2.3
resolvectl

먼저 인터페이스 정보를 보면 eth0이 10.0.2.15를 가지는 것을 볼 수 있다.

이 부분에 대해 명확하게 더 분석을 하진 않았으나, virtualbox를 이용하는 경우에 vagrant와 통신할 때 사용되는 인터페이스는 항상 모든 vm이 해당 대역과 주소를 할당받는 것으로 보인다.
다른 vm에 접속해도 해당 주소는 동일하게 출력되는데, 위 대역에서는 고정된 ip들이 몇 있다.
가령ssh 접속은 10.0.2.2주소를 가지는 내부 게이트웨이로부터 들어오는 것을 확인할 수 있다.

DNS 질의를 처리해주는 리졸버 역시 10.0.2.3으로 주소가 고정돼있다.

이를 통해 vagrant에서 virtualbox 프로바이더를 사용할 때는 항상 해당 부분들을 고정된 방식으로 사용하는 것이 아닐까 추측한다.

클러스터 정보 확인

간단하게 현재 클러스터의 정보를 확인해본다.

k cluster-info
k get nodes -owide

처음 클러스터를 세팅할 때 join 설정에서 node-ip 정보를 kubelet 추가 인자로 전달했던 값이 클러스터 노드의 ip로 그대로 반영된다.

cni 세팅을 다 하고 찍은 샷이긴 한데, 원래는 각 노드마다 kube-proxy가 배치된다.

프록시가 정확하게 노드의 internal-ip를 받았는지도 명확하게 체크해주자.

플래널 설치

첫 실습에서는 기존 환경에 실리움을 배치하는 실습 과정을 거친다.^[2]
이를 위해 먼저 플래널을 헬름으로 설치한다.

kubectl create ns kube-flannel
kubectl label --overwrite ns kube-flannel pod-security.kubernetes.io/enforce=privileged

helm repo add flannel https://flannel-io.github.io/flannel/
helm show values flannel/flannel

cat << EOF > flannel-values.yaml
podCidr: "10.244.0.0/16"
flannel:
  args:
  - "--ip-masq"
  - "--kube-subnet-mgr"
  - "--iface=eth1"  
EOF

helm install flannel --namespace kube-flannel flannel/flannel -f flannel-values.yaml

# 확인 : install-cni-plugin, install-cni
kc describe pod -n kube-flannel -l app=flannel

간단하게 cni를 배치하는데 성공했다.

플래널은 실제 설치되는 것도 딱 flannel 데몬 뿐이다.

간단하게 어플리케이션을 배치해서 통신이 제대로 되는지 확인해본다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webpod
spec:
  replicas: 2
  selector:
    matchLabels:
      app: webpod
  template:
    metadata:
      labels:
        app: webpod
    spec:
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            - labelSelector:
                matchExpressions:
                  - key: app
                    operator: In
                    values:
                      - sample-app
              topologyKey: "kubernetes.io/hostname"
      containers:
        - name: webpod
          image: traefik/whoami
          ports:
            - containerPort: 80
      terminationGracePeriodSeconds: 1
---
apiVersion: v1
kind: Service
metadata:
  name: webpod
  labels:
    app: webpod
spec:
  selector:
    app: webpod
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  type: ClusterIP
---
apiVersion: v1
kind: Pod
metadata:
  name: curl-pod
  labels:
    app: curl
spec:
  nodeName: k8s-ctr
  containers:
    - name: curl
      image: nicolaka/netshoot
      command: ["sleep", "36000"]
  terminationGracePeriodSeconds: 1

curl을 날릴 파드를 마스터 노드에 배치하여 다른 워커 노드로의 통신이 가능한지 확인한다.

k exec -ti curl-pod -- curl webpod

통신이 정상적으로 이뤄지는 것을 확인할 수 있다.

트래픽을 보낸 curl-pod의 ip가 그대로 남아있는 것을 확인할 수 있다.

실리움 마이그레이션

운영 중인 클러스터의 cni를 어떻게 실리움으로 마이그레이션할 수 있을까?^[3]
노드마다 세팅된 cni의 기본 설정은 /etc/cni/net.d/에 있으며 kubelet이 파드를 세팅할 때 이 경로에 적힌 설정을 이용한다.
실리움은 다른 cni가 있을 때 이미 존재할 cni의 파일을 바꿔치기해준다.

실리움은 여기에서 하이브리드 모드를 지원해주기에, 노드 별 점진적 마이그레이션이 가능하다.
달리 말해 클러스터에 두 개의 오버레이가 있도록 허용한다는 것.
그래서 파드는 실리움 관리 파드, 아닌 파드 둘 다 접근할 수 있게 된다.
(대신 최소한 둘은 다른 대역이어야 한다.)

일단 다음의 전제조건이 요구된다.

• Cilium이 사용할 새로운 별도의 Cluster CIDR
• Cluster Pool IPAM 모드 사용
• 별도의 오버레이(프로토콜 또는 포트)
• Linux 라우팅 스택을 사용하는 기존 네트워크 플러그인 (예: Flannel, Calico, AWS-CNI)

Cilium 마이그레이션은 아직 다음에 대해 제대로 테스트되지 않았다고 하니 참고하자.

• BGP 기반 라우팅
• IP 패밀리 변경 (예: IPv4에서 IPv6로)
• Cilium이 체인 모드로 동작하는 경우
• 기존 NetworkPolicy 제공자

수행할 전체 절차를 요약하면 다음과 같다.

1. Cilium을 보조 모드로 설치
2. 각 노드를 순차적으로 마이그레이션
   1. 안전한 마이그레이션을 위해 각 노드는 corden을 먼저 진행한다.
3. 기존 cni 제거
4. (선택 사항) 각 노드 다시 부팅
   • iptables, nic 등의 각종 설정 정보와 kubelet, cri 설정을 한꺼번에 초기화하려면 재부팅이 가장 편한 것 같다.

참고로 마이그레이션 동안 실리움을 통한 네트워크 폴리시는 비활성화된다.

마이그레이션 작업

본격적으로 들어가보자면 먼저 실리움 헬름 변수 세팅을 한다.

operator:
  unmanagedPodWatcher:
    restart: false # Migration: Don't restart unmigrated pods
routingMode: tunnel # Migration: Optional: default is tunneling, configure as needed
tunnelProtocol: vxlan # Migration: Optional: default is VXLAN, configure as needed
tunnelPort: 8473 # Migration: Optional, change only if both networks use the same port by default
cni:
  customConf: true # Migration: Don't install a CNI configuration file
  uninstall: false # Migration: Don't remove CNI configuration on shutdown
ipam:
  mode: "cluster-pool"
  operator:
    clusterPoolIPv4PodCIDRList: ["10.245.0.0/16"] # Migration: Ensure this is distinct and unused
policyEnforcementMode: "never" # Migration: Disable policy enforcement
bpf:
  hostLegacyRouting: true # Migration: Allow for routing between Cilium and the existing overlay

여기 있는 설정 중 ipam, cni 필드쪽은 필수적으로 해줘야 한다.
기존 플래널이 vxlan(기본 8472 포트)를 사용하고 있어 포트를 8473으로 바꿨고, 파드 cidr도 10.244.0.0/16에서 수정했다.

필요한 나머지 세팅 부분은 dry run을 통해 기본값으로 세팅한다.
(근데 막상 해보면 바뀌는 값은 그다지 없는 것 같다.)

cilium install --version 1.17.6 --values values-migration.yaml --dry-run-helm-values > values-initial.yaml

이제 실제로 실리움을 설치하고 대기한다.

helm repo add cilium https://helm.cilium.io/
helm install cilium cilium/cilium --namespace kube-system --values values-initial.yaml
cilium status --wait

대략 3분 기다리니 성공적으로 모든 컴포넌트가 배치됐다.

클러스터 파드 부분을 보면 현재 실리움에 의해 관리되지 않는 파드(0/5)들을 확인할 수 있다.
플래널 테스트를 위해 설치한 파드들은 재기동된 적 없으니 실리움의 관리를 받을 여지도 없다.

이제 노드 별로 마이그레이션을 진행하기 위해 노드에 적용될 설정 리소스를 만들어야 한다.

cat <<EOF | kubectl apply --server-side -f -
apiVersion: cilium.io/v2
kind: CiliumNodeConfig
metadata:
  namespace: kube-system
  name: cilium-default
spec:
  nodeSelector:
    matchLabels:
      io.cilium.migration/cilium-default: "true"
  defaults:
    write-cni-conf-when-ready: /host/etc/cni/net.d/05-cilium.conflist
    custom-cni-conf: "false"
    cni-chaining-mode: "none"
    cni-exclusive: "true"
EOF

참고로 이 설정은 마이그레이션 간에만 잠깐 사용하고 나중에는 없앨 것이다.
노드 셀렉터에 명시된 라벨을 가진 노드는 이 설정의 적용을 받게 된다.
이제부터는 각 노드를 드레인하고 실리움 파드 재기동을 통한 정책 적용, 이후 노드 설정을 초기화하고 모든 컨테이너를 재시작하기 위해 노드를 재부팅하는 과정을 거친다.

NODE="k8s-w2"
kubectl cordon $NODE
kubectl drain --ignore-daemonsets $NODE
kubectl label node $NODE --overwrite "io.cilium.migration/cilium-default=true"

kubectl -n kube-system delete pod --field-selector spec.nodeName=$NODE -l k8s-app=cilium
kubectl -n kube-system rollout status ds/cilium -w

vagrant ssh $NODE -c "sudo reboot"

나는 호스트 환경에서 kubectl을 사용하고 있어 바로 vagrant로 vm을 재기동했는데, 만약 마스터 노드에서 실행하고 있다면 아랫줄은 커스텀해야 한다.

성공적으로 파드가 축출되고, 재시작이 되는지 확인해본다.

이후 제대로 ip 대역이 변경되는지 확인한다.

cilium status --wait
kubectl get -o wide node $NODE
kubectl -n kube-system run --attach --rm --restart=Never verify-network \
  --overrides='{"spec": {"nodeName": "'$NODE'", "tolerations": [{"operator": "Exists"}]}}' \
  --image ghcr.io/nicolaka/netshoot:v0.8 -- /bin/bash -c 'ip -br addr && curl -s -k https://$KUBERNETES_SERVICE_HOST/healthz && echo'

정상적으로 세팅이 된 노드라면 재기동 시 kubelet과 containerd가 다시 시작될 것이다.
이때 실리움이 제대로 적용되는지 확인하기 위해 파드를 띄워본다.

파드 내부에서 인터페이스를 찍었을 때 10.245.0.0 대역을 받은 것을 확인할 수 있는데, 이것은 실리움이 설정된 대역이므로 정상적으로 실리움이 파드의 네트워킹을 전담하고 있다는 것을 파악할 수 있다.

kubectl uncordon $NODE

uncordon까지 하면 마이그레이션 작업은 완료된다.

나머지 노드들에 대해서도 동일하게 작업해준다.
마스터 노드가 하나라 재부팅 시 잠시 클러스터로서의 기능은 중단되나, 신뢰 원천이 달리 있는 것도 아니라 마이그레이션 간 별 문제는 발생하지 않는다.

플래널 세팅 시 테스트했던 파드들이 재기동 이후에도 통신이 문제 없이 진행되면 성공이다!

모든 파드가 실리움의 파드 ip 대역을 받고 있다.

cilium 명령어를 통해서도 모든 파드가 관리되고 있는 것을 확인할 수 있다.

정리 작업

작업이 완료됐다면 마이그레이션을 위해 사용했던 노드 설정 리소스를 지우고 라벨을 제거해준다.

k -n kube-system delete ciliumnodeconfigs.cilium.io cilium-default
k label nodes k8s-w2 io.cilium.migration/cilium-default-
k label nodes k8s-w1 io.cilium.migration/cilium-default-
k label nodes k8s-ctr io.cilium.migration/cilium-default-

가장 마지막으로 남은 작업은 이전에 설치된 플래널을 걷어내는 것이다.

helm -n kube-flannel uninstall flannel

이렇게 헬름만 제거해도 충분하지만, 노드에 남은 자투리 파일도 전부 제거하고 싶다면 /opt/cni/bin, /etc/cni/net.d에 있는 플래널 관련 파일들을 지워주면 된다.

실수로 인터페이스, iptables를 리셋하는 것을 잊었는데 막상 노드 재부팅을 하니 다 사라져있어서 직접적으로 할 필요는 없는 것으로 보인다.

실리움 업그레이드

현재 실리움은 공식 문서에 나온 기본 설정 값을 가지고 있다.
그러나 스터디에서 진행된 실습 환경으로 구성하기 위해서는 추가적인 기능들을 설정해야 한다.
여기에서 설정할 사항은 다음과 같다.

• 네이티브 라우팅 모드
• kube-proxy 대체
• bpf 기반 마스커레이딩

이 작업은 간단하게 헬름 업그레이드를 통해 수행할 수 있다.

helm upgrade cilium cilium/cilium --version 1.17.6 --namespace kube-system \
--reuse-values \
--set k8sServiceHost=192.168.10.100 --set k8sServicePort=6443 \
--set kubeProxyReplacement=true \
--set routingMode=native \
--set autoDirectNodeRoutes=true \
--set ipam.mode="cluster-pool" \
--set ipam.operator.clusterPoolIPv4PodCIDRList={"172.20.0.0/16"} \
--set ipv4NativeRoutingCIDR=172.20.0.0/16 \
--set endpointRoutes.enabled=true \
--set installNoConntrackIptablesRules=true \
--set bpf.masquerade=true \
--set ipv6.enabled=false

(추후에 알았는데, nativeroutingcidr 관련 세팅은 제대로 적용되지 않았다)

제대로 배포가 됐다면 더 이상 kube-proxy는 필요하지 않으므로 삭제한다.

kubectl -n kube-system delete ds kube-proxy
kubectl -n kube-system delete cm kube-proxy

kube-proxy가 없는 상태로 서비스로 통하는 트래픽이 제대로 이뤄지는지 확인하기 위해, 이전 예제를 없앴다가 다시 만들어본다.

문제 없이 통신이 가능한 것을 확인할 수 있다.

마무리

현 실습은 마이그레이션 작업 자체에 초점을 맞추어 실리움 설정 커스텀을 세밀하게 신경쓰지 못했다.
이후에 해당 부분을 조금 보강하면 좋을 것 같다.

이전 글, 다음 글

• 1W - 실리움 기본 소개: 1
• 1W - 기본 실리움 탐색 및 통신 확인: 3

다른 글 보기

관련 문서

지식 문서, EXPLAIN

기타 문서

참고